Mergeall — Backup and Sync Your Stuff Your Way

Version:
    3.3, October 16, 2022 (all-packages release)

Author:
    © M. Lutz (https://learning-python.com), 2014-2022

License:
    Provided freely, but with no warranties of any kind.  This program is
    open source and is yours to use and copy as you like for personal use.
    For quality and attribution purposes, any bulk redistributions must 
    include in full and unaltered form this file, and file "UserGuide.html"
    and folders "docetc" and "test" from the top level of this package.  

    Please note: Mergeall changes a destination folder in-place by design.
    It backs up items changed or removed during a run and supports rollbacks,
    but you should understand its purpose before running it on your content. 
    Read section "Usage Cautions" in file "UserGuide.html" before using it.

Fetch: 
    From "https://learning-python.com/mergeall.html" download and unzip:

      - Mergeall.app.zip    (macOS app)
      - Mergeall-64bit.zip  (Windows executable)
      - Mergeall.zip        (Linux executable)
      - Mergeall-source.zip (source code)

    All packages are Mergeall 3.3.  The macOS, Windows, and Linux packages 
    use Python 3.8 and were built on Catalina, Windows 11, and Ubuntu 20,
    respectively.  See Package Usage Basics below for more install details.

Start:
    To launch the program's GUI, run the unzipped folder or its file:

      - Mergeall.app            (macOS app) 
      - launch-mergeall-GUI.exe (Windows executable)
      - launch-mergeall-GUI     (Linux executable)  
      - launch-mergeall-GUI.pyw (source code)

    Besides its syncs GUI, Mergeall includes a system of scripts which may 
    be run from a console command line: mergeall.py, deltas.py, diffall.py, 
    cpall.py, and more.  See Package Usage Basics below for more run details.

Docs:
    Open UserGuide.html in any web browser to read the main user guide.
    Select 'Help' in the GUI to view that document in most distributions. 

Screenshots:
    See UserGuide.html or folder docetc/docimgs for GUI samples.

Configs:
    Edit mergeall_configs.py to customize Mergeall's appearance and behavior.

Backups:
    When backups are enabled, Mergeall saves all files deleted or changed by
    a run in the __bkp__ folder of the "TO" destination.  See UserGuide.html.

Tools:
    Mergeall is coded in Python, and uses tkinter/Tk for its GUI. 
    macOS frozen apps are built with py2app; others use PyInstaller.  
    For using the source package, Python 3.X is strongly recommended. 

Versions:
    3.3, Oct-2022: normalization changes, all download packages rebuilt
    3.3, Mar-2022: minor GUI changes, apps and executables rebuilt for 3.3
    3.3, Dec-2021: major release - Unicode normalization for filename matching
    3.2, Oct-2021: major release - deltas.py deferred-updates script and mode
    3.1, Dec-2017: minor upgrade - folder modtimes, Linux flushes, "-u"
    3.0, Jun-2017: major release - GUI redesign, macOS port, cruft skips, app/exes

    Versions 3.3 and 3.2 were initially released in the source-code package
    only, but 3.3 was later pushed out to all app and executable packages too.
    See docetc/MoreDocs/Revisions.html for all versions and changes.

Upgrades:
    To install a new version of Mergeall in the future, save and restore
    any customizations you've made in mergeall_configs.py.

Updates:
    Watch https://learning-python.com/post-release-updates.html
    for new-release announcements and additional usage pointers.

------------------------------------------------------------------------------

Package Usage Basics

Mergeall is available as full source code, a macOS app, and executables
for Windows and Linux.  In brief, here are the formats' tradeoffs:

Source code
  Pros: the ultimate in portability; may have more recent updates; may 
        be run with a more recent Python and Tk; required on Android
  Cons: requires and dependent on a separately installed Python

Apps and executables 
  Pros: integrate better with your computer's GUI; do not require any 
        additional install steps; generally immune to future changes
        in both the Python programming language and Tk they use
  Cons: not portable, may lose functionality over time as platforms morph 

Apps and executables are like most installed software and launch with a 
click, though source code can also be launched quickly with shortcuts.

Also note that the source-code package may grow more recent that the 
apps and executables over time, and hence is generally preferred.

The following sections give the fundamentals of each format's usage:

    - macOS App Package
    - Windows Executable Package
    - Linux Executable Package
    - Source-Code Package

------------------------------------------------------------------------------

macOS App Package

    The macOS (f.k.a. OS X) app runs only on Macintosh systems, but requires 
    no Python install and better supports the Macintosh user experience.

    To install:
        Fetch file "Mergeall.app.zip", unzip it by a double-click (or other), 
        and drag the resulting Mergeall.app to your /Applications folder in 
        Finder to access it from Launchpad.  You can also move Mergeall.app 
        and create aliases to it anywhere else on your computer.
    
    To Run:
        Click "Mergeall.app" to start the program (or run the app any other way).
        Running Mergeall.app automatically launches Mergeall's GUI launcher,
        the same as running the source-code package's launch-mergeall-GUI.pyw.
        From the GUI, configure and run Mergeall to propagate your content.

        Clicking Mergeall's app icon or Dock entry while the program is running 
        automatically deiconifies (unhides) its main window, and always lifts
        it above other windows on screen (handy to locate it in a busy session).
        Double-click the app and single-click the Dock to make this work.

    Files:
        Your mergeall_configs.py file is located inside the unzipped app's 
        folder, at path:
        
            Mergeall.app/Contents/Resources

        Navigate to this nested folder in Finder by a right-click on 
        Mergeall.app and Show Package Contents (or use "ls" in Terminal).
        Your UserGuide.html is in the same folder, but can also be 
        accessed by the program's "Help" button.

    Scripts:
        All Mergeall scripts are frozen executables in the app's folder:
        
            Mergeall.app/Content/MacOS
        
        The scripts have no ".py" extension in this format, but otherwise run 
        exactly as documented.  No separate Python install is required to run 
        these from command lines in Terminal.  For example, if you've drug the
        unzipped folder to your /Applications, the following work in Terminal:

        CPALL:
          /Applications/Mergeall.app/Contents/MacOS/cpall dirFrom dirTo -skipcruft

        DIFFALL:
          /Applications/Mergeall.app/Contents/MacOS/diffall dir1 dir2 -skipcruft
          /Applications/Mergeall.app/Contents/MacOS/diffall dir1 dir2 -skipcruft -u > log.txt

        MERGEALL:
          /Applications/Mergeall.app/Contents/MacOS/mergeall dirFrom dirTo -report
          /Applications/Mergeall.app/Contents/MacOS/mergeall dirFrom dirTo -auto -backup -skipcruft

        LAUNCHERS:
          /Applications/Mergeall.app/Contents/MacOS/launch-mergeall-Console 
          /Applications/Mergeall.app/Contents/MacOS/launch-mergeall-GUI  (the same as an app click)

        OTHER:
          /Applications/Mergeall.app/Contents/MacOS/deltas
          /Applications/Mergeall.app/Contents/MacOS/rollback
          /Applications/Mergeall.app/Contents/MacOS/fix-fat-dst-modtimes folder -add
          /Applications/Mergeall.app/Contents/MacOS/nuke-cruft-files -help

        Note that source-code versions of these scripts are also included in
        the app's Contents/Resources folder for their documentation, but will
        not generally run in this form and location; use the frozen executables
        in Contents/MacOS instead. 

    Versions: 
        The macOS app was built on macOS (a.k.a. OS X) version 10.15 Catalina
        on an Intel-based system, using Python 3.8.  It is expected to work on 
        later macOS versions too regardless of chip architectures, though this 
        remains to be verified, as does support for earlier macOS versions.

    Known issues:
        Due to limitations in the underlying software stack, some non-ASCII
        characters may be replaced for display; see the user guide for details.

        Due to the underlying Tk toolkit, messages may scroll slowly in the
        GUI.  It may speed scrolling to minimize/restore the window to the Dock.

        macOS Mojave users: this iteration of macOS temporarily broke Tk GUIs
        for the sake of a dark-mode change.  For a fix and work-around, see:
        https://learning-python.com/post-release-updates.html#macosmojavestartup.

        In the 3.3 app, widgets lose their active styling when the GUI window
        is minimized and restored; click elsewhere and back to reset.  The 3.1
        app's fix for this is disabled, as it no longer works and may abort.

        [This following does not apply to the 3.3 Feb-2022 macOS app.]  
        Due to a flaw in the underlying Tk toolkit, closed windows may leave
        zombie items in Dock menus; these can be safely ignored.  See also 
        https://learning-python.com/post-release-updates.html#appexpose.

------------------------------------------------------------------------------

Windows Executable Packages

    The Windows executables run only on Windows systems, but require
    no Python install and better support the Windows user interface.

    NEW: as of the Feb-2022 executable for Mergeall 3.3, only a 64-bit 
    build is provided online.  Older references to a 32-bit build are 
    now moot, but see "Versions" below for options on older machines.

    To install:
        Fetch file "Mergeall-64bit.zip" and unzip it on your computer 
        Copy the unzipped folder to \Users\<you>\Desktop or elsewhere 
        to save it.  Make Desktop shortcuts to the unzipped folder's 
        executable (per the next section) for quick access as desired.

    To Run:
        Click on the unzipped folder's "launch-mergeall-GUI.exe" file to run.  
        This automatically starts Mergeall's GUI launcher, the same as 
        running the source-code package's script launch-mergeall-GUI.pyw.
        From the GUI, configure and run Mergeall to propagate your content.
        File "launch-mergeall-console.exe" runs the lesser-used console interface.

    Files:
        Your UserGuide.html, mergeall_configs.py, and utility-script exes are 
        are all located at the top level of the same folder as the main ".exe"
        executable (the folder created by unzipping the download).

    Scripts:
        Mergeall's extra utility scripts in this package are all provided as
        executables that have a ".exe" extension instead of a ".py" and can be 
        run without a local Python install, but otherwise work the same.  For 
        example, the source package's diffall.py and rollback.py become ".exe"
        executables in this package (the ".exe" in these is usually optional):

            Mergeall-64bit\diffall.exe folder1 folder2 -skipcruft
            Mergeall-64bit\rollback.exe
       
        Scripts' ".py" source files are also included for their in-file 
        documentation, but some may not run in this form; use their .exes.
        See the macOS app's documentation above for more utility scripts.        

    Versions: 
        The Windows executable comes in only 64-bit form, as denoted by its 
        zipfile name.  This works only on 64-bit systems; to use Mergeall on 
        older 32-bit machines, either run its source-code package, or build a
        32-bit executable from Mergeall's build script in the build/ folder.

        The sole 64-bit executable was built on Windows 11 21H2, using Python
        3.8; it should work on this and later Windows, though support for 
        later and earlier Windows is unverified.

    Known issues: 
        Due to limitations in the underlying software stack, some non-ASCII
        characters may be replaced for display; see the user guide for details.

        Startups may be briefly delayed due to PyInstaller folder extracts.  
        An SSD system drive is recommended for quicker starts, but use the 
        source-code package if this is problematic on slower machines.

        IMPORTANT: Tk GUIs like Mergeall's may have blurry fonts on some versions
        of Windows when first started.  For a simple one-time fix, see this note:
        https://learning-python.com/post-release-updates.html#win10blurryguis.

        Antivirus programs can have a massive impact on Windows performance,
        in one measured case slowing a diffall.py run by a factor of 5 (1 hour 
        versus 12 minutes).  As usual, disable such programs for faster runs.

------------------------------------------------------------------------------

Linux Executable Package

    The Linux executable runs only on Linux systems, but requires no
    Python install and may better support the Linux user interface.

    To install:
        Fetch file "Mergeall.zip" and unzip it on your computer.  Copy the
        unzipped folder to your home, desktop, or other folder to make it 
        easy to access, and make desktop shortcuts to the executable as 
        desired.  

    To Run:
        Click on the unzipped folder's "launch-mergeall" file to run.  
        This automatically starts Mergeall's GUI launcher, the same as 
        running the source-code package's script launch-mergeall-GUI.pyw.
        From the GUI, configure and run Mergeall to propagate your content.
        File "launch-mergeall-console.exe" runs the lesser-used console interface.
 
    Files:
        Your UserGuide.html, mergeall_configs.py, and utility-script executables
        are all located at the top level of the same folder as the main 
        executable (the folder created by unzipping the download).

    Scripts:
        Mergeall's extra utility scripts in this package are all provided as
        executables that have no extension instead of a ".py" and can be 
        run without a local Python install, but otherwise work the same.  
        For example, the source package's diffall.py and rollback.py become
        Linux executables in this package:

            Mergeall/diffall folder1 folder2 -skipcruft
            Mergeall/rollback

        Scripts' ".py" source files are also included for their in-file 
        documentation, but some may not run in this form; use the executables.
        See the macOS app's documentation above for more utility scripts.        

    Versions: 
        The sole Linux executable was built on Ubuntu Linux 20.04 on a 64-bit 
        system, using Python 3.8.  It is known to work on this and other versions
        of Ubuntu and is expected to work on some other distributions of Linux,
        but this is to be verified.  If it fails on your system, use the 
        source-code Mergeall package instead.

    Known issues:
        Due to limitations in the underlying software stack, some non-ASCII
        characters may be replaced for display; see the user guide for details.

        Startups may be briefly delayed due to PyInstaller folder extracts.  
        An SSD system drive is recommended for quicker starts, but use the 
        source-code package if this is problematic on slower machines.

        exFAT is now in the Linux kernel but still maturing, and there are 
        new notes on using FAT-32 and exFAT removable drives on your platform:
        https://learning-python.com/post-release-updates.html#mergealllinuxmodtimes.

        [This following does not apply to the 3.3 Feb-2022 Linux executable.]  
        As of Dec-2020, the 2017 Linux executables are no longer recommended,
        due to font breakage resulting from platform morph.  For details, see:
        https://learning-python.com/post-release-updates.html#linux2017executables.

------------------------------------------------------------------------------

Source-Code Package 

    The source-code version of Mergeall runs on all flavors of macOS, 
    Windows, and Linux, but requires a separately installed Python.
    The source-code also runs on all recent versions of Android.

    To Install:
        Fetch file "Mergeall-source.zip" and unzip it on your computer.
        Also fetch and install a usable Python 3.X if one is not already
        present.  On macOS and Linux, also install the tkinter/Tk toolkit 
        if needed.  See the user guide's "Platform Basics" for details.

    To Run:
        Run "launch-mergeall-GUI.pyw" in the unzipped folder to launch 
        the program's GUI, using any Python program-launching technique 
        on your platform: Windows icon clicks, IDLE, command lines, macOS 
        Python Launcher, etc.  You can also run the file from within 
        the PyEdit GUI (see learning-python.com/pyedit).
        
    Files:
        Your UserGuide.html, mergeall_configs.py, and utility scripts 
        are all located in the same folder as the main scripts' file
        (the folder created by unzipping the download).

    Scripts:
        As this package includes full source code, all its non-GUI tools
        are available as script text files.  Run its top-level mergeall.py, 
        deltas.py, diffall.py, cpall.py, and the fix-*.py utilities from a
        console command line as usual.  See scripts for argument details.

    Versions:
        Source code is platform-neutral and is not dependent on the 
        version of your operating system.  This package runs on all
        versions of macOS, Windows, and Linux in common use today.
        
        The source-code package does, however, require and assume a
        separately installed Python on your computer: download one 
        for your platform from www.python.org/downloads if Python is 
        not already installed.  
 
        Mergeall's source code has been verified to run on all Python 
        3.X through 3.10, and has no third-party install requirements.
        Later Python versions are expected to work too, but 3.10 is 
        the latest version verified.  Due to its support, Python 3.X 
        is strongly recommended for content with non-ASCII filenames.

    Known issues:
        Due to limitations in the underlying software stack, some non-ASCII
        characters may be replaced for display; see the user guide for details.

        On macOS, messages may scroll slowly in the GUI.  It may speed message
        scrolling to minimize the window to the Dock and restore it later.

        On recent versions of macOS, widgets lose their active styling when the
        GUI window is minimized and restored; click elsewhere and back to reset.  

        On macOS with older Pythons, due to a flaw in the underlying Tk toolkit, 
        closed windows may leave zombie but harmless items in Dock menus.  See 
        https://learning-python.com/post-release-updates.html#appexpose.

        On Windows, you may need to "set PYTHONIOENCODING=utf8" to avoid 
        errors for non-ASCII output messages, when using command lines and
        redirecting output to files.  See UserGuide.html#pythonioencoding.

        On Windows, Tk GUIs like Mergeall's may have blurry fonts when first
        started on some versions.  For a simple fix, see this usage note:
        https://learning-python.com/post-release-updates.html#win10blurryguis.

        On Windows, antivirus programs can have a massive impact on performance,
        in one measured case slowing a diffall.py run by a factor of 5 (1 hour 
        versus 12 minutes).  As usual, disable such programs for faster runs.

        On Linux, exFAT is now in the kernel but still maturing, and there are 
        new notes on using FAT-32 and exFAT removable drives on this platform:
        https://learning-python.com/post-release-updates.html#mergealllinuxmodtimes.

        On Android, Mergeall scripts work normally in Termux or similar, 
        and its GUI works in Pydroid 3 but requires code patches.  See:
        https://learning-python.com/mergeall-android-scripts/_README.html,
        https://learning-python.com/using-tkinter-programs-on-android.html.

        On Android 11 and later, Mergeall does not have direct access to USB 
        drives.  To perform to-phone syncs on these devices, see this package:
        https://learning-python.com/android-deltas-sync/,
        https://learning-python.com/android-deltas-sync/_README.html.

------------------------------------------------------------------------------
[end]
